
@codemod-utils/files
Utilities for handling files
What is it?
@codemod-utils/files
wraps the synchronous methods from node:fs
, node:path
, and glob
to help you update many files in the same way.
API
Many of the methods make use of the file path, a string that represents the location of a file. Therefore, I recommend learning findFiles
first, as it returns the paths of all files that match the search criteria.
copyFiles
Copies files from one directory (source) to another (destination). Creates the destination directory if it doesn't exist.
Example
Copy LICENSE.md
and README.md
from the project root to the folder ember-container-query
.
import { copyFiles } from '@codemod-utils/files';
const filePathMap = new Map([
['LICENSE.md', 'ember-container-query/LICENSE.md'],
['README.md', 'ember-container-query/README.md'],
]);
copyFiles(filePathMap, {
projectRoot,
});
createDirectory
Creates the directories specified in the file path, if they don't exist yet.
⚠️ Likely, you won't need this method but createFiles
instead.
Example
Create the folder ember-container-query
if it doesn't exist.
import { createDirectory } from '@codemod-utils/files';
const newFilePath = 'ember-container-query/LICENSE.md';
const destination = join(projectRoot, newFilePath);
createDirectory(destination);
createFiles
Create files. Creates the destination directory if it doesn't exist.
Example
Create LICENSE.md
and README.md
in the project root.
import { createFiles } from '@codemod-utils/files';
const fileMap = new Map([
['LICENSE.md', 'The MIT License (MIT)'],
['README.md', '# ember-container-query'],
]);
createFiles(fileMap, {
projectRoot,
});
findFiles
Often, you will want a codemod step to apply to select files. findFiles
provides the paths of all files that match your search criteria (i.e. glob pattern, ignore list, and project root). The paths are sorted in alphabetical order.
Example
Find all component templates in an Ember app.
import { findfiles } from '@codemod-utils/files';
const filePaths = findFiles('app/components/**/*.hbs', {
projectRoot,
});
You can provide ignoreList
, an array of file paths or glob patterns, to exclude files.
Example
Find all component classes in an Ember app.
import { findfiles } from '@codemod-utils/files';
const filePaths = findFiles('app/components/**/*.{js,ts}', {
ignoreList: ['**/*.d.ts'],
projectRoot,
});
To look for multiple types of files, you can pass an array of glob patterns (pattern A or pattern B or ...).
Examples
import { findfiles } from '@codemod-utils/files';
const filePaths = findFiles([
'LICENSE.md',
'README.md',
], {
projectRoot,
});
import { findfiles } from '@codemod-utils/files';
const filePaths = findFiles([
'app/components/**/*.hbs',
'tests/integration/components/**/*-test.{js,ts}',
], {
projectRoot,
});
getPackageRoots
Returns the roots of all packages in a project.
Example
Analyze each package by reading package.json
.
import { readPackageJson } from '@codemod-utils/json';
const packageRoots = getPackageRoots({
projectRoot,
});
packageRoots.forEach((packageRoot) => {
const packageJson = readPackageJson({ projectRoot: packageRoot });
});
mapFilePaths
Creates a mapping of file paths, which can then be passed to copyFiles
or moveFiles
.
Example
Map LICENSE.md
to ember-container-query/LICENSE.md
(and similarly for README.md
).
import { mapFilePaths } from '@codemod-utils/files';
const filePaths = ['LICENSE.md', 'README.md'];
const filePathMap = mapFilePaths(filePaths, {
from: '',
to: 'ember-container-query',
});
moveFiles
Moves files from one directory (source) to another (destination). Creates the destination directory if it doesn't exist. Removes the source directory if it is empty.
Example
Move LICENSE.md
and README.md
from the project root to a folder named ember-container-query
.
import { moveFiles } from '@codemod-utils/files';
const filePathMap = new Map([
['LICENSE.md', 'ember-container-query/LICENSE.md'],
['README.md', 'ember-container-query/README.md'],
]);
moveFiles(filePathMap, {
projectRoot,
});
parseFilePath
Parses a file path, similarly to parse()
from node:path
, but correctly handles file extensions with more than one .
, e.g. .d.ts
and .css.d.ts
.
Example
import { parseFilePath } from '@codemod-utils/files';
const filePath = 'src/components/navigation-menu.d.ts';
const { base, dir, ext, name } = parseFilePath(filePath);
removeDirectoryIfEmpty
Removes the directories specified in the file path, if they are empty.
⚠️ Likely, you won't need this method but removeFiles
instead.
Example
Remove the folder ember-container-query
if it is empty.
import { removeDirectoryIfEmpty } from '@codemod-utils/files';
const filePath = 'ember-container-query/LICENSE.md';
removeDirectoryIfEmpty(filePath, {
projectRoot,
});
removeFiles
Removes files. Removes the source directory if it is empty.
Example
Remove LICENSE.md
and README.md
from the project root.
import { removeFiles } from '@codemod-utils/files';
const filePaths = ['LICENSE.md', 'README.md'];
removeFiles(filePaths, {
projectRoot,
});
renamePathByDirectory
Forms a new file path by altering the path's directory.
Example
Prepare to move components from addon
to ember-container-query/src
.
import { renamePathByDirectory } from '@codemod-utils/files';
const oldFilePath = 'addon/components/container-query.hbs';
const newFilePath = renamePathByDirectory(oldFilePath, {
from: 'addon',
to: 'ember-container-query/src',
});
Compatibility
Contributing
See the Contributing guide for details.
License
This project is licensed under the MIT License.